Referencing Session Variables on the Client
Description
Session variables are only available on the server unless they are explicitly published to the client. Published session variable are read-only and cannot be modified by the client.
Discussion
Grid and UX Components allow you to 'publish' session variables to the client, making session variables available to client side. Published session variables can be referenced in client-side expressions, including:
- Calculated Fields
- Show/hide Expressions
- Enable Expressions
- Dynamic Images
- Conditional Style Expressions
Published session variables can also be referenced in custom JavaScript in client-side events.
The Published Session Variables property is used to define the session variables to publish to the client.
Published session variables can also be defined using the Publish SESSION Variables link found in many of the client-side dialogs for defining expressions.
When the component is executed, the values of the published session variables are stored in the Component's JavaScript object. The variables can be accessed directly through the _vars sub-object of the component's JavaScript object or using the getSessionVariable() method (available for both the UX and Grid Components.)
For example, if you publish a session variable called 'VAR1', you can use the following JavaScript to read its value (the name is always uppercase):
{dialog.object}.getSessionVariable('VAR1');The following example shows how you can set the text of a button control in the UX to the value of a session variable (session.var1).
//The following code is in the onRenderComplete client-side event
var sVar1;
sVar1 = {dialog.object}.getSessionVariable('VAR1');
// Test the value!
// getSessionVariable returns undefined if the
// session variable is not available on the client.
if(typeof sVar1 != 'undefined') {
//Set the text shown on 'BUTTON_1':
{dialog.object}.setValue('BUTTON_1', sVar1);
}Referencing Published Session Variables in Client-side Expressions
Published session variables can be used in client-side expression. Client-side expressions are case-sensitive. The session variable must be referred to using the 'SESSION.' prefix and using uppercase. For example:
SESSION.COMPANYNAME = "Alpha"
Modifying Published Session Variables
Session variables on the client are read-only. They cannot be modified. In order to change the value of a session variable, an Ajax Callback is required.
Similarly, if a session variable changes on the server, it will not be updated on the client until an Ajax Callback is made from the client.
Methods
The following client-side functions can be used to work with published session variables in JavaScript:
- Method
- Description
- {dialog.object}.getSessionVariable
Get the value of a session variable.
- {grid.object}.getSessionVariable
Get the value of a session variable.
Videos
Using Session Variables in Client-side Enable Expressions
In this video, we show how to use published session variables in a client-side enable expression.
See Also